feat(auth): add the WorkOS device grant client - #1570

🏁 Script executed:

#!/bin/bash
set -euo pipefail

rg -n -C 4 \
  'type WorkosDeps|baseUrl|authorization_endpoint|token_endpoint|user_management|oauth2/device_authorization|oauth2/token' \
  src

Repository: qawolf/cli

Length of output: 50366

🤖 get_repo_knowledge executed:

get_repo_knowledge qawolf/cli /tmp/coderabbit-repo-knowledge/qawolf-cli-66811854/conventions /tmp/coderabbit-repo-knowledge/qawolf-cli-66811854/learnings

Length of output: 6333

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- WorkOS implementation ---'
for f in \
  src/shell/workos/requestDeviceAuthorization.ts \
  src/shell/workos/pollDeviceToken.ts \
  src/shell/workos/refreshAccessToken.ts \
  src/shell/workos/types.ts \
  src/shell/workos/send.ts \
  src/shell/workos/config.ts
do
  echo "--- $f"
  cat -n "$f"
done

printf '%s\n' '--- WorkOS tests relevant to request contracts ---'
for f in \
  src/shell/workos/requestDeviceAuthorization.test.ts \
  src/shell/workos/pollDeviceToken.test.ts \
  src/shell/workos/refreshAccessToken.test.ts
do
  echo "--- $f"
  cat -n "$f"
done

Repository: qawolf/cli

Length of output: 38087

🌐 Web query:

site:workos.com/docs/reference/workos-connect/cli-auth WorkOS Connect device authorization token endpoint oauth2

💡 Result:

WorkOS Connect implements the OAuth 2.0 Device Authorization Flow (RFC 8628) to enable CLI applications and devices with limited input to authenticate users [1][2]. The token exchange process occurs at the standard token endpoint: Endpoint: POST https://authkit_domain/oauth2/token To exchange a device code for access, ID, and refresh tokens, the client must perform a POST request to this endpoint with the following parameters [1][3]: Required Parameters: - grant_type: Must be set to urn:ietf:params:oauth:grant-type:device_code [1][3]. - device_code: The device code string obtained previously from the device authorization endpoint [1][3]. - client_id: The client ID of your WorkOS Connect application [1][3]. - client_secret: The secret key associated with your WorkOS Connect application [1][3]. The client should poll this endpoint repeatedly until the user has authorized the request, the request is declined, or the device code expires [1][3]. The polling interval is specified in the initial response from the device authorization endpoint [2]. Prior to this step, the device must initiate the flow by calling the device authorization endpoint [2]: - Endpoint: POST https://authkit_domain/oauth2/device_authorization [2] - Required Parameters: client_id [2] - Optional Parameters: scope (e.g., openid, profile, email) [2] This initial call returns the device_code, user_code, and the verification_uri where the user must authenticate [2].

Citations:

• 1: https://workos.com/docs/reference/workos-connect/cli-auth/device-code-grant
• 2: https://workos.com/docs/reference/workos-connect/cli-auth/authorize-device
• 3: https://workos.com/docs/reference/workos-connect/cli-auth

• src/shell/workos/requestDeviceAuthorization.ts#L18-L21 (this comment)
• src/shell/workos/requestDeviceAuthorization.test.ts#L51-L57
• src/shell/workos/pollDeviceToken.test.ts#L59-L69
• src/shell/workos/refreshAccessToken.ts#L33-L37
• src/shell/workos/refreshAccessToken.test.ts#L45-L55

🤖 get_repo_knowledge executed:

get_repo_knowledge qawolf/cli /tmp/coderabbit-repo-knowledge/qawolf-cli-66811854/conventions

Length of output: 2905

🏁 Script executed:

#!/bin/bash
set -eu
printf '%s\n' '--- send.ts ---'
cat -n src/shell/workos/send.ts | sed -n '1,140p'
printf '%s\n' '--- related WorkOS symbols ---'
rg -n -C 3 'sendWorkosRequest|pollDeviceToken|invalid_grant|isTransientStatus|retryable' src test tests 2>/dev/null || true

Repository: qawolf/cli

Length of output: 34176

🌐 Web query:

WorkOS OAuth device authorization grant refresh token rotation invalid_grant token endpoint documentation

💡 Result:

WorkOS implements OAuth 2.0 refresh token rotation as part of its authentication lifecycle to enhance security [1][2][3]. When you exchange a refresh token for a new access token, WorkOS frequently rotates the refresh token, meaning the previously used token becomes invalid and must be discarded in favor of the newly issued one [4][2][3]. Regarding the invalid_grant error and token rotation: 1. Grace Period: To prevent issues caused by race conditions (e.g., concurrent requests) or slow network retries, WorkOS enforces a 30-second grace period after each refresh token exchange [1][2]. During this window, if you replay the recently used refresh token, WorkOS will return the same set of rotated tokens rather than an error [1][2]. 2. Invalid Grant (Terminal Error): Once the grace period expires, any attempt to use a previously exchanged (spent) refresh token is considered a terminal failure [1][2]. In this case, the WorkOS token endpoint returns an invalid_grant error (HTTP 400), indicating the session is no longer valid and the user must re-authenticate [1][2]. 3. Handling Errors: - Terminal (invalid_grant): Clear the session and redirect the user to the sign-in flow [1][2]. - Transient (e.g., Network/Timeout/5xx/429): Retain the current session and retry the request using the same refresh token, ideally with exponential backoff [1][2]. For the Device Authorization Grant specifically, the flow involves polling the token endpoint using the device_code [5][6][7]. Once authorized, this exchange yields access and refresh tokens [6][8]. The same principles regarding token rotation and error handling apply once you move into the refresh token lifecycle [1][3]. If you receive an invalid_grant during the initial device code polling, it indicates the device code is malformed, invalid, or has already been consumed [7].

Citations:

• 1: https://workos.com/docs/authkit/session-resilience
• 2: https://workos.com/blog/ios-sdk-token-storage-refresh-guide
• 3: https://workos.com/docs/authkit/sessions.md
• 4: https://workos.com/docs/reference/authkit/authentication/refresh-token
• 5: https://workos.com/docs/reference/authkit/cli-auth/device-authorization
• 6: https://workos.com/docs/reference/workos-connect/cli-auth/device-code-grant
• 7: https://workos.com/docs/reference/authkit/cli-auth/error-codes
• 8: https://workos.com/docs/reference/workos-connect/cli-auth

🌐 Web query:

site:workos.com/docs device authorization grant refresh token rotation invalid_grant WorkOS

💡 Result:

In WorkOS, an invalid_grant error during the refresh token flow—including in the context of flows that provide refresh tokens, such as device authorization—typically indicates that the refresh token is terminal [1]. This occurs when the token has been revoked, is expired, has already been used (and the grace period has elapsed), or is otherwise no longer valid [1]. WorkOS employs refresh token rotation to enhance security [1][2]. When you use a refresh token to obtain a new access token, the system may issue a new refresh token, and the previously used one is retired [1]. Key details regarding this process include: 1. Rotation and Grace Periods: When tokens rotate, there is often a short grace period during which reusing the "old" refresh token is safe and idempotent; you will receive the same new tokens back [1]. Once this grace period elapses, any attempt to use the old token will return an invalid_grant error [1]. 2. Terminal Failures: An invalid_grant error in this context is considered a terminal failure [1]. This signifies that the session is genuinely over, and the application must clear the session and force the user to re-authenticate [1]. 3. Handling Concurrent Requests: In environments where multiple processes or workers might attempt to use the same refresh token concurrently (e.g., in a distributed system), one worker might consume the token while another is still holding it, leading to an invalid_grant if the grace period has passed [3]. It is recommended to give each process or worker its own session state to avoid this [3]. 4. Device Authorization: While the device authorization grant is used to initiate the flow and obtain initial tokens, subsequent refreshes follow the standard refresh token logic [4][5]. If you receive an invalid_grant when using the device_code grant itself, it usually means the device code is malformed, expired, or already used [6][4]. If you are encountering this error, your application should catch the invalid_grant (400 Bad Request), clear local session state, and redirect the user to sign in again [1]. Do not retry on a terminal invalid_grant error; retries should only be attempted for transient network errors or server-side issues (e.g., 5xx, 429) [1][3].

Citations:

• 1: https://workos.com/docs/authkit/session-resilience
• 2: https://workos.com/docs/reference/authkit/authentication/refresh-token
• 3: https://workos.com/docs/authkit/testing
• 4: https://workos.com/docs/reference/authkit/cli-auth/error-codes
• 5: https://workos.com/docs/reference/workos-connect/cli-auth/device-code-grant
• 6: https://workos.com/docs/reference/authkit/cli-auth/device-authorization

🏁 Script executed:

#!/bin/bash
set -eu
cat -n src/shell/workos/send.ts | sed -n '1,130p'
rg -n -C 5 'sendWorkosRequest|pollDeviceToken|isTransientStatus|retryable|invalid_grant' src .github 2>/dev/null || true

Repository: qawolf/cli

Length of output: 43391

🏁 Script executed:

#!/bin/bash
set -eu
printf '%s\n' '--- implementation ---'
cat -n src/shell/workos/send.ts | sed -n '1,130p'
printf '%s\n' '--- callers and tests ---'
rg -n -C 5 'sendWorkosRequest|pollDeviceToken|refresh.?token|device.?code|invalid_grant|retryable' src test tests 2>/dev/null || true
printf '%s\n' '--- public WorkOS documentation references ---'
curl -L --max-time 10 -sS 'https://workos.com/docs/reference/oauth/token' | grep -Eio '.{0,100}(device_code|refresh_token|invalid_grant|rotation|single[- ]use).{0,180}' | head -40 || true

Repository: qawolf/cli

Length of output: 50366

🏁 Script executed:

#!/bin/bash
set -eu
printf '%s\n' '--- device polling callers ---'
rg -n -C 8 'pollDeviceToken\(' src --glob '*.ts'
printf '%s\n' '--- refresh retry callers ---'
rg -n -C 8 'refreshAccessToken\(' src --glob '*.ts'
printf '%s\n' '--- unreadable-success tests ---'
cat -n src/shell/workos/pollDeviceToken.test.ts | sed -n '205,245p'

Repository: qawolf/cli

Length of output: 27430

🏁 Script executed:

#!/bin/bash
set -eu
printf '%s\n' '--- polling and refresh callers ---'
rg -n -C 6 'pollDeviceToken\(|refreshAccessToken\(' src --glob '*.ts' | head -160
printf '%s\n' '--- unreadable-success tests ---'
cat -n src/shell/workos/pollDeviceToken.test.ts | sed -n '205,245p'

Repository: qawolf/cli

Length of output: 13930